2.3.2 签名计算详解

签名计算步骤：

1. 从原始请求中提取出用于签名的字符串：签名串 = 提取签名字符串(原始请求)；
2. 通过API ID和API密钥计算签名密钥：签名密钥 = 计算签名密钥(API ID, API密钥)；
3. 计算签名：签名 = HMAC-SHA256(签名密钥, 签名串) ；
4. 将签名、时间戳、API ID和nonce加入请求头部，得到最终请求（详见请求头部详解）。

1、签名串提取方法

组成要素：请求路径、query参数、body参数

• 计算公式：

  签名串 = 请求路径 + ? + query参数 + & + body参数

  当body参数不存在时： 签名串 = 请求路径 + ? + query参数

  当query参数不存在时： 签名串 = 请求路径 + ? + body参数

  当body参数和query参数都不存在时： 签名串 = 请求路径

• 请求路径

  一个url可以分解为，schema、hostname、port、pathname、search这几个部分。

  以下面这个url为例，该url并非aTrust控制台真实存在的url，此处只是一个示例：https://1.1.1.1:4433/api/v1/admin/login?username=sf&password=123

  schema = https 
  hostname = 1.1.1.1 
  port = 4433 
  pathname = /api/v1/admin/login 
  search = username=xiaoming&password=123
  

  其中我们拼接签名串所使用的请求路径即为pathname这个部分，即/api/v1/admin/login

• query参数

  签名串中使用的query参数需要对key进行ASCII排序

  例如：因为p的字母序小于u，所以password=123&username=sf是正确的，而username=sf&password=123是错误的

• body参数

  POST请求中的json，为了跨语言兼容，这里必须是紧凑格式的json，逗号和分号后不能有空格和换行，

  如：{"key1":"value1"}

• 签名串提取示例

  • 原始API接口输入为：

    POST https://1.1.1.1:4433/api/v1/admin/login?username=sf&password=123 content-type: application/json;charset=UTF-8 
    Request Payload 
    {
     "status": 1,
     "type": "test" 
    }
    

  • 签名串输出结果为：

    /api/v1/admin/login?password=123&username=sf&{"status":1,"type":"test"}
    

2、签名密钥计算方法

组成要素：API ID、API密钥、时间戳、随机数nonce

• 计算公式

  签名密钥 = 'appId=' + API ID + '&' + 'appSecret=' + API密钥 + '&' + 'timestamp=' + 时间戳 + '&' + 'nonce=' + nonce

• API ID

  参考 2.2.2 获取API ID和API 密钥

• API密钥

  参考 2.2.2 获取API ID和API 密钥

• 时间戳

  时间戳为Unix时间戳格式，单位为秒，10位长度的正整数。

  如：时间为 2021年 08月 21日 星期六 14:25:00 CST ，时间戳格式为1629527100。

• 随机数nonce

  nonce为一个随机数，由数字字母加中划线组成的字符串，长度2~128位，建议使用uuidv4，如：f5f0fe63-5b3e-4e44-908c-b95758b6d7e4

说明：

nonce是个随机字母+数字组成的字符串，优先建议使用uuidv4的方法计算。若在测试过程中使用uuidv4计算有难度，也可直接使用举例的字符串进行测试。

• 签名密钥示例

  • 输入：

    API ID：8165305
    API密钥：aebd2e3c5ea2449aa2928c102f9db276
    客户端当前时间：2021年 08月 21日 星期六 14:25:00 CST。转化为对应的时间戳：1629527100
    随机数：f5f0fe63-5b3e-4e44-908c-b95758b6d7e4
    

  • 输出：

    签名密钥为：appId=8165305&appSecret=aebd2e3c5ea2449aa2928c102f9db276&timestamp=1629527100&nonce=f5f0fe63-5b3e-4e44-908c-b95758b6d7e4
    

3、 签名计算方法

注意：

1. 签名密钥和签名串均为UTF-8编码

2. 签名最终以十六进制编码表示

• 计算公式

  签名 = HMAC-SHA256(签名密钥, 签名串)

• 示例

  • 输入：

    签名串：/api/v1/admin/login?password=123&username=sf&{"status":1,"type":"test"}
    
    签名密钥：appId=8165305&appSecret=aebd2e3c5ea2449aa2928c102f9db276&timestamp=1629527100&nonce=f5f0fe63-5b3e-4e44-908c-b95758b6d7e4
    

  • 输出：

    签名：5eec2b22d4ad87daac420d9ef1476346da46ecabbfb2ed18a744d571cdde7756
    

• 签名算法代码：

  零信任提供了三种编程语言的签名算法（HMAC-SHA256）示例，分别是Python、JavaScript、java，签名算法示例详情见 demo 使用说明